home *** CD-ROM | disk | FTP | other *** search
/ Aminet 13 / Aminet 13 - August 1996.iso / Aminet / dev / e / AutoBuild13.lha / AutoBuild / AutoBuild.doc < prev   
Text File  |  1996-06-21  |  10KB  |  209 lines
  1.                      **********************************
  2.                      *          Autobuild v1.3        *
  3.                      * © 1994-1996 Jan Hendrik Schulz *
  4.                      **********************************
  5.  
  6.                                Indroduction
  7.                                ~~~~~~~~~~~~
  8.    What is autobuild? Autobuild is an automatic build tool for AmigaE. It
  9. can do the same think like the build tool that came with AmigaE v3 if it is
  10. used to build programms which are splitted over several modules, but it
  11. does it automaticly. That meens, you need no .build-file to define the
  12. dependencies etc.
  13.  
  14.                                  History
  15.                                  ~~~~~~~
  16. v1.0   - First public release
  17.  
  18. v1.1   - Sources without PROC and EXPORT causing no error anymore.
  19.        - v1.0 doesn't noticed a failing EC or Mac2E sometimes and doesn't
  20.          stop. I hope, this bug is fixed now.
  21.  
  22. v1.2   - All Mac2E features are removed, because the new AmigeE v3.1 makes
  23.          Mac2E obsolet.
  24.  
  25. v1.3   - VERBOSE keyword added.
  26.        - Errormessage 'can't find source to build "xxx.m".' now displays
  27.          additional info 'used by "abc.e".' if possible.
  28.  
  29.  
  30.                     Why using autobuild and not build?
  31.                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  32.    If you are writing a big program and splitt the source into several
  33. modules, you have to change the .build-file everytime when you introduce
  34. a new module, or if a source after some changes needs other modules.
  35.    With autobuild, if you have changed the MODULE information in the source,
  36. autobuild sees automaticly the new dependence and acts accordingly.
  37.    And last but not least, unlike build, autobuild sees circular dependen-
  38. cies between the files. And if you call it with FORCE, every file is still
  39. builded only once! (Maybe the new E v3.1+ build does this too?!)
  40.  
  41.  
  42.                               Requirements
  43.                               ~~~~~~~~~~~~
  44.    To use autobuild you need at least Kickstart 2.04 and AmigaE v3.1
  45. If you still use AmigaE v2.1 then use autobuild v1.1 with Mac2E.
  46.  
  47.  
  48.                           How to use autobuild?
  49.                           ~~~~~~~~~~~~~~~~~~~~~
  50.    Autobuild must be called from the shell and it has the following syntax:
  51.  
  52.  TARGET,FORCE=F/S,PRIVATONLY=PO/S,QUIET=Q/S,ECOPTS=EO/K,ECPATH=EP/K,VERBOSE=V/S
  53.  
  54. TARGET      is the name of the file that should be build. (Without the .m
  55.             if it is a module!)
  56.  
  57. FORCE       tells autobuild to build all files, even if they are allready
  58.             uptodate. (Even with FORCE, every file is build only once!)
  59.  
  60. PRIVATONLY  Normaly autobuild compares the filedate of EVERY used module
  61.             with the filedate of the target to find out, if the target is
  62.             up to date (newer). If you use PRIVATONLY, only the private
  63.             modules (those which names begin with a '*') are testet and
  64.             not those in EMODULES:
  65.  
  66. QUIET       Only error-messages (and the output of EC) are printed.
  67.  
  68. ECOPTS      here you can give additional arguments for the EC-call. You
  69.             should write doublequotes around them! Autobuild calls EC like
  70.             this: EC <file> <ecopts>
  71.             Example: autobuild target ECOPTS "QUIET"
  72.  
  73. ECPATH      You can tell autobuild where to find EC and than autobuild
  74.             copies EC to RAM:EC (if needed) and uses RAM:EC instead of EC.
  75.             Example: autobuild target ECPATH "Work:AmigaE/Bin/EC"
  76.  
  77. VERBOSE     For every analysed source, autobuild prints a list of the
  78.             modules used by this source. If PRIVATONLY is used too, only
  79.             the private modules are listed.
  80.  
  81.  
  82.                           The .autobuild file
  83.                           ~~~~~~~~~~~~~~~~~~~
  84.    To make the autobuild call easier, autobuild looks for a file called
  85. ".autobuild" in the currend directory and if it exists, the first line of
  86. this file is passed through ReadArgs() with the template above. So normaly
  87. you can execute autobuild without any arguments. If you use arguments and
  88. additionaly there is an .autobuild-file, both are mixed like this:
  89.  
  90. TARGET, ECOPTS and ECPATH:
  91.    If you give them with the commandline, the corresponding .autobuild
  92.    setting is ignored.
  93.    
  94. FORCE, PRIVATEONLY, QUIET and VERBOSE:
  95.    The commandline and the .autobuild-settings are Eor()ed.
  96.  
  97.  
  98.                         How does autobuild work?
  99.                         ~~~~~~~~~~~~~~~~~~~~~~~~
  100.    To see, how autobuild works, I think it's the best way to show you how
  101. the most important PROC of autobuild - build() - works. If you call
  102. autobuild e.g. with 'autobuild abc' then build() is called with 'abc' as
  103. target. And build() works like this:
  104.  
  105.                         *-----------------------*
  106.                         |   PROC build(target)  |
  107.                         *-----------+-----------*
  108.                                     |
  109.                      +--------------+--------------+
  110.                      | Look into 'target.e' to see |
  111.                      | which emodules are used by  |
  112.                      | this source.                |
  113.                      +--------------+--------------+
  114.                                     |
  115.                      +--------------+--------------+
  116.                      | Call build() for every used |
  117.                      | privat emodule to make them |
  118.                      | up to date if necessary     |
  119.                      +--------------+--------------+
  120.                                     |
  121.                      ?--------------+--------------?
  122.                      |      Exists 'target'        |
  123.              +---NO--+     (or 'target.m') ?       |
  124.              |       ?--------------+--------------?
  125.              |                      | YES
  126.              |       ?--------------+--------------?
  127.              |       |  Is 'target.e' newer than   |
  128.              +--YES--+ 'target' (or 'target.m') ?  |
  129.              |       ?--------------+--------------?
  130.              |                      | NO
  131.              |       ?--------------+--------------?
  132.              |       | Is at least one of the used |
  133.              +--YES--+ emodules newer than 'target'|
  134.               \      |      (or 'target.m') ?      |
  135.                \     ?--------------+--------------?
  136.                 \                   | NO
  137.    +-------------+-------------+    |
  138.    | Call EC to build an up to |    |
  139.    | date 'target'-file        |    |
  140.    | (or 'target.m'-file )     |    |
  141.    +-------------+-------------+    |
  142.                  |                  |
  143.                  +----------------+ |
  144.                                    \|
  145.                                *----+-----*
  146.                                |  RETURN  |
  147.                                *----------*
  148.  
  149.    The above shoud only give an idea what the PROC build() does. The real
  150. PROC build() works a little bit different! It has some lists in memory to
  151. build every file only once, and to look for the filedate of a file only
  152. once for example, but the result is the same.
  153.  
  154.  
  155.                           Some important infos!
  156.                           ~~~~~~~~~~~~~~~~~~~~~
  157. -  Autobuild reads the source only until it finds the first PROC or EXPORT
  158. keyword to make things faster. Is there no PROC or EXPORT, the whole file
  159. is read.
  160.  
  161. -  To make autobuild not to complicate, the keywords MODULE, PROC and
  162. EXPORT must be on the beginning of the line! (No leading spaces or tabs.)
  163. If they are not at the beginning of the line, autobuild doesn't see them!
  164. On the other hand, if you use the keyword in other situations (e.g.
  165. MODULE after an OPT), make shure that it is NOT at the beginning of the
  166. line to make it invisible for autobuild!
  167.  
  168.  
  169.                           Copyright and Author
  170.                           ~~~~~~~~~~~~~~~~~~~~
  171.          Autobuild is (c) copyright 1994-1996 Jan Hendrik Schulz
  172.  
  173.    Redistributing autobuild is allowed, as long as all files are included
  174. and unchanged, and as long as no profit is made by distributing autobuild!
  175.  
  176.    Autobuild is giftware, if you use it, send me something usefull
  177. (at least a postcard or an e-mail).
  178.  
  179.            My address:   Jan Hendrik Schulz
  180.                          Elsässer Str. 19
  181.                          22049 Hamburg
  182.                          Germany
  183.  
  184.                e-mail:   schulz_j@informatik.fh-hamburg.de
  185.                          schulzjan@dame.de
  186.  
  187.  
  188.                              Disclaimer
  189.                              ~~~~~~~~~~
  190.     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
  191.  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  192.  HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
  193.  OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
  194.  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  195.  PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  196.  PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE
  197.  COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  198.  
  199.     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  200.  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE
  201.  PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
  202.  GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  203.  USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
  204.  OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
  205.  THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
  206.  PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
  207.  POSSIBILITY OF SUCH DAMAGES.
  208.  
  209.